feat(types): declare a gantt bar as an object on both published faces - #8405

Fixes #7365

A gantt BAR is now declared an OBJECT on both published faces. An authored
null bar is refused at validate, by its own name, at items[i].items[j].

What was wrong

TimelineSchema.items[].items[] — a gantt row's bars — was z.array(z.any())
in the zod mirror and any[] on the TypeScript face. So this ordinary JSON was
green through validate:

{ "type": "timeline", "variant": "gantt",
  "items": [{ "label": "R", "items": [null] }] }

and the author's only signal came later, from the render-time date diagnostic:

Unusable gantt date range — items[0].items[0].startDate is undefined, which is
not a valid date.

That names the wrong fault. The bar is null; startDate is a key the author
never wrote. This is the mis-naming class objectui#7164 repaired for ROWS, one
level down.

The ruling this implements

Director seat, decision batch #71, 2026-09-07; maintainer reply verbatim,
unaltered and untranslated: 「其他同意」. Option B.

objectui#7164 narrowed the row and stopped at the bar level deliberately,
and wrote the stop down in both faces' docblocks. This PR supersedes that stop
knowingly, per the ruling — and removes the prose recording it rather than
qualifying it, so the next reader does not re-derive a gap that is now closed.
That re-derivation is how this card came to exist.

⛔ Option A is refused, not deferred. timeline.gantt.unusableRange.malformedRow's
copy is untouched, no fourth path level was added to that sentence, and the ten
language packs are untouched. The render-time date diagnostic remains the
defined outcome for anything that still reaches it — the renderer stays only
ever MORE lenient than validate, never the reverse.
⛔ packages/plugin-timeline/src/renderer.tsx was READ ONLY here; its row
predicate belongs to objectui#7364 and is not touched.

The change

Re-derived on the merged base c4b3750 (the ruling's line numbers were stale;
so were the ones taken at dispatch, because main moved again in between):

⚠️ z.array(z.any()) occurs three times in that mirror; :243 and :258 are
data: on Table schemas and are NOT this target. The edit is anchored on the
enclosing TimelineRowSchema, not on a grep.

The TS face is the TypeScript spelling of the mirror at each level —
a Record KEYED BY string WITH unknown VALUES for the mirror's
z.object({}).passthrough(), and a string index signature for the passthrough
itself. (That type is spelled in words throughout this body, never in its
angle-bracket form — see the note at the foot.)

Nothing beyond the bar's object-ness is narrowed. A bar's own keys
(title / startDate / endDate / variant?) stay undeclared and open, so
items: [{}] still parses. TimelineSchema serves more than gantt, so this
was checked one variant over: a feed item carries no items key at all and is
untouched — pinned both ways in the new test.

Stock measurement — required, because this narrows a published accept set

Counted on 289d146 and re-measured unchanged on c4b3750, across apps/ ·
examples/ · content/ · packages/types/examples/:

timeline nodes  : 4
rows            : 11
bars TOTAL      : 5
bars WELL-FORMED (object) : 5   <-- FIRING CONTROL
bars null       : 0
bars non-object : 0

The zero is a reading, not an empty search. Two firing controls:

1. The same walker reported the five well-formed bars it did find, with their
   paths.
2. A planted null bar and a planted numeric bar, added to a scratch copy of
   the gantt fixture, were both found and named:
   examples/planted.json :: .items[0].items[2] and
   .items[1].items[2] (non-object: 7).

⇒ Nothing in this repository moves. ⚠️ hotcrm is a separate repository and is
not reachable from this checkout: it is unmeasured, and named as such rather
than counted as zero.

The docs page's gantt example is a TS literal, not JSON, so it is covered by a
different instrument — see the ablation below.

Evidence

Reverse verification of the TS face, against the rebuilt .d.ts a consumer
actually resolves (@object-ui/plugin-timeline has no src path alias, so it
reads dist/data-display.d.ts):

The two legs' full error sets differ by exactly that one line. Restore proven by
an empty git diff HEAD, not by an exit code.

Ablation proving check:doc-snippets actually measures the docs gantt
example — a green gate over 632 blocks does not by itself say this block is
one of them. Planting a null bar in content/docs/plugins/plugin-timeline.mdx
turned it red at exactly the expected place:

[semantic]  content/docs/plugins/plugin-timeline.mdx:215:9
            TS2322: Type 'null' is not assignable to type 'Record KEYED BY string WITH unknown VALUES'.
Semantic phase: 632 of 632 block(s) judged, 1 failed.

Restored and verified by blob hash 362f6d19ff9aba4656976c6cb870abab69e23f47
matching the HEAD blob, plus an empty git diff HEAD.

New pin — packages/types/src/__tests__/timeline-items-bar-shape-7365.test.ts,
modelled on objectui#7164's. It carries the ruling's pin ({ items: [{ label: 'R', items: [null] }] } fails at items[0].items[0]; a well-formed bar
passes), asserts the refusal never mentions startDate, re-asserts objectui#7164's
row-level refusals as unchanged, and rebuilds the PREVIOUS declaration in-test
so the "before" column is measured against today's base rather than remembered.

Gates — all on the final head 630f54c, exit code captured before any pipe

Root test, lint and type-check run the whole farm and are CI's; the
package-scoped equivalents above are complete for this diff — @object-ui/types
is the only package whose source changed, and @object-ui/plugin-timeline is
the only consumer that reads the narrowed key.

Serial constraint, and the answer it produced

packages/types/src/zod/data-display.zod.ts is shared with PR #8354
(objectui#7760, draft, parked at the same gate), which edits TreeNodeSchema at
about :323. This card's region is the timeline row items at about :732.

That PR pins seven header figures on
packages/types/src/__tests__/zod-mirror-parity.test.ts, so the stop condition
was: does this change move any row there?

No. Zero rows added, removed or moved — the file is byte-identical to
origin/main (git diff origin/main -- packages/types/src/__tests__/zod-mirror-parity.test.ts
is empty), and it was not edited. Both faces narrowed symmetrically, so
there is no divergence to record: WiderThanDeclaredKeys still resolves to
never for TimelineSchema::items, which the parity test's type-level ledger
assertions confirm by passing under tsc -p tsconfig.test.json.

Contract review

Clause-② is yes — this narrows a published accept set: a null gantt bar is
legal today and will not be after this lands. needs:contract-review is hung on
this PR and on the card. This PR stays draft, is not enqueued, and has no
auto-merge armed; parking green is the intended end state.

Changeset: @object-ui/types minor. Breaking semantics, minor per this
repo's rule that its own breaking changes never declare major (the fixed group
follows @objectstack's cadence); the breaking half is spelled out in the
changeset body.

Notes

• Related cards, deliberately not touched here and NOT acted on by this PR:
  objectui#7364 owns the renderer's row predicate, and objectui#7164 is the
  row-level card this one sits below. Both stay open; this PR acts on 7365 only.
• ⛔ No HTML comment markers appear anywhere in this body, and no generic is
  written in its angle-bracket form — this platform's body sanitizer eats short
  tag-shaped fragments, including inside backticks and fenced blocks, so type
  arguments are spelled as words (Record KEYED BY string WITH unknown VALUES)
  and read literally in the source files, where they carry their real spelling.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QtGhnU3WnnWyiWeYQhw2aX

Generated by Claude Code